<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  
  

  


  

  <head>
    <title>
      libusbwin32_documentation – libusb-win32
    </title>
        <link rel="search" href="/apps/trac/libusb-win32/search" />
        <link rel="help" href="/apps/trac/libusb-win32/wiki/TracGuide" />
        <link rel="alternate" href="/apps/trac/libusb-win32/wiki/libusbwin32_documentation?format=txt" type="text/x-trac-wiki" title="Plain Text" />
        <link rel="start" href="/apps/trac/libusb-win32/wiki" />
        <link rel="stylesheet" href="/apps/trac/libusb-win32/chrome/common/css/trac.css" type="text/css" /><link rel="stylesheet" href="/apps/trac/libusb-win32/chrome/common/css/wiki.css" type="text/css" />
        <link rel="shortcut icon" href="/apps/trac/libusb-win32/chrome/common/trac.ico" type="image/x-icon" />
        <link rel="icon" href="/apps/trac/libusb-win32/chrome/common/trac.ico" type="image/x-icon" />
      <link type="application/opensearchdescription+xml" rel="search" href="/apps/trac/libusb-win32/search/opensearch" title="Search libusb-win32" />
    <script type="text/javascript" src="/apps/trac/libusb-win32/chrome/common/js/jquery.js"></script><script type="text/javascript" src="/apps/trac/libusb-win32/chrome/common/js/trac.js"></script><script type="text/javascript" src="/apps/trac/libusb-win32/chrome/common/js/search.js"></script>
    <!--[if lt IE 7]>
    <script type="text/javascript" src="/apps/trac/libusb-win32/chrome/common/js/ie_pre7_hacks.js"></script>
    <![endif]-->
    <script type="text/javascript">
      jQuery(document).ready(function($) {
        $("#content").find("h1,h2,h3,h4,h5,h6").addAnchor("Link to this section");
      });
    </script>
  <link type="text/css" href="/apps/trac/libusb-win32/chrome/site/ha-css/default2.css" rel="stylesheet" />

    <link rel="stylesheet" type="text/css" href="http://static.sourceforge.net/css/develop/hosted.php?secure=0&amp;1382583234" media="all" />

    <!-- BEGIN: AdSolution-Tag 4.2: Global-Code [PLACE IN HTML-HEAD-AREA!] -->
    <!-- DoubleClick Random Number -->
    <script type="text/javascript">
      dfp_ord=Math.random()*10000000000000000;
      dfp_tile = 1;
    </script>
	
    <!-- End DoubleClick Random Number -->
    <!-- END: AdSolution-Tag 4.2: Global-Code -->

</head>
  <body>


<script type="text/javascript">
  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-32013-36']);
  _gaq.push(['_trackPageview']);
  _gaq.push(['t2._setAccount', 'UA-36130941-3']);
  _gaq.push(['t2._trackPageview']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();
</script>

<div id="sf_header">
    <div class="sfh_n">
        <ol class="sfh_n_ol">
            <li class="sfh_n_li"><span><a href="/" id="sf_logo"><strong>SourceForge</strong></a></span></li>
            <li class="sfh_n_li"><span><a href="/projects/libusb-win32" title="Summary page hosted on SourceForge.net">Summary</a></span></li>
            <li class="sfh_n_li"><span><a href="/projects/libusb-win32/files" title="Files available for download">Files</a></span></li>                            <li class="sfh_n_li"><span><a href="/projects/libusb-win32/support">Support</a></span></li>
                        <li class="sfh_n_li"><span><a href="/support">Report Spam</a></span></li>
                            <li class="sfh_n_li right"><span><a href="/user/registration/" title="Get a SourceForge.net account">Create account</a></span></li>
                <li class="sfh_n_li right"><span><a href="/account/login.php" title="Log in and gain access to additional features">Log in</a></span></li>
                    </ol>
    </div>
</div>
<div id="fad1happ" class="ads">
   <script type="text/javascript">
   //<![CDATA[
    document.write('<script src="http://ad.doubleclick.net/adj/ostg.sourceforge/cons_hosted_apps_p11_spons;pg=default;sz=728x90;tile='+dfp_tile+';tpc=project;tpc=libusb-win32;ord='+dfp_ord+'?" type="text/javascript"><\/script>');
     dfp_tile++;
    //]]>
    </script>
</div>
    

	<div id="doc3" class="yui-t6">
		<div id="bd">
			<a name="content"></a>
<!-- End Header -->
    <div id="banner">
      <div id="header">
        <h1><a href="http://sourceforge.net/projects/libusb-win32/">libusb-win32</a></h1>
      </div>
      <form id="search" action="/apps/trac/libusb-win32/search" method="get">
        <div>
          <label for="proj-search">Search:</label>
          <input type="text" id="proj-search" name="q" size="18" value="" />
          <input type="submit" value="Search" />
        </div>
      </form>
      <div id="metanav" class="nav">
    <ul>
      <li class="first"><a href="/apps/trac/libusb-win32/prefs">Preferences</a></li><li><a href="/apps/trac/libusb-win32/wiki/TracGuide">Help/Guide</a></li><li class="last"><a href="/apps/trac/libusb-win32/about">About Trac</a></li>
    </ul>
  </div>
    </div>
    <div id="mainnav" class="nav">
    <ul>
      <li class="first active"><a href="/apps/trac/libusb-win32/wiki">Wiki</a></li><li><a href="/apps/trac/libusb-win32/timeline">Timeline</a></li><li><a href="/apps/trac/libusb-win32/roadmap">Roadmap</a></li><li><a href="/apps/trac/libusb-win32/browser">Browse Source</a></li><li><a href="/apps/trac/libusb-win32/report">View Tickets</a></li><li class="last"><a href="/apps/trac/libusb-win32/search">Search</a></li>
    </ul>
  </div>
    <div id="main">
      <div id="ctxtnav" class="nav">
        <h2>Context Navigation</h2>
          <ul>
            <li class="first "><a href="/apps/trac/libusb-win32/wiki/WikiStart">Start Page</a></li><li><a href="/apps/trac/libusb-win32/wiki/TitleIndex">Index</a></li><li><a href="/apps/trac/libusb-win32/wiki/libusbwin32_documentation?action=history">History</a></li><li class="last"><a href="/apps/trac/libusb-win32/wiki/libusbwin32_documentation?action=diff&amp;version=8">Last Change</a></li>
          </ul>
        <hr />
      </div>
    <div id="content" class="wiki">
      <div class="wikipage searchable">
        
          <p>
The following documentation is based on <a class="ext-link" href="http://libusb.sourceforge.net/doc/"><span class="icon">libusb-0.1 API documentation</span></a> by Johannes Erdfelt.
</p>
<p>
Preface
</p>
<blockquote>
<p>
The purpose of this document is to explain the libusb-win32 API and how to use it to make a USB aware application. Any suggestions, corrections and comments regarding this document should be sent to the libusb-win32 developers mailing list.
</p>
</blockquote>
<h2 id="I.Introduction">I. Introduction</h2>
<p>
This documentation will provide an overview of how the v0.1 libusb API works and relates to USB. It is assumed that the reader has a good understanding of the USB 2.0 specification. The USB 2.0 specification can be found the USB Implementers Forum website (<a class="ext-link" href="http://www.usb.org"><span class="icon">http://www.usb.org</span></a>).  libusb-0.1 works under Linux, FreeBSD, NetBSD, OpenBSD; Darwin/MacOS X and Solaris. libusb-win32 is API compatible with libusb-0.1 but also includes some new features.
</p>
<h2 id="II.API">II. API</h2>
<p>
This is the external API for applications to use. The API is relatively lean and designed to closely correspond with the USB 2.0 specification.
</p>
<p>
<strong>Devices and interfaces</strong>
</p>
<p>
The libusb API ties an open device to a specific interface. This means that if you want to claim multiple interfaces on a device, you should open the device multiple times to receive one usb_dev_handle for each interface you want to communicate with. Don't forget to call usb_claim_interface().
</p>
<p>
Timeouts in libusb are always specified in milliseconds.
</p>
<p>
libusb uses both abstracted and non abstracted structures to maintain portability.
</p>
<p>
All functions in the original libusb v0.1 are synchronous, meaning the functions block and wait for the operation to finish or timeout before returning execution to the calling application. libusb-win32 adds some asynchronous APIs. libusb-1.0 has more asynchronous API support.
</p>
<p>
There are two types of return values used in libusb v0.1. The first is a handle returned by usb_open(). The second is an int. In all cases where an int is returned, &gt;= 0 is a success and &lt; 0 is an error condition.
</p>
<p>
<strong>Timeout</strong>
The unit for timeout value is ms.
</p>
<p>
Under Linux libusb-0.1 (which only supports synchronous API), timeout value of 0 means infinite. libusb-win32 version 1.2.4.7 and later will follow this for synchronous API. Before that, it behaves differently from Linux libusb-0.1.
</p>
<p>
Since Windows (same for Linux and Mac OS X) is not an RTOS, it is not a good idea to use small timeout value like 10ms or 100ms. 
</p>
<p>
<strong>Caveats of synchronous transfer when timeout happens</strong>
How synchronous API works:
1) Submits read request to driver
2) Waits the specified timeout using <a class="missing wiki">WaitForSingleObject?</a>()
</p>
<ol class="loweralpha"><li>if a wait timeout occurred, send abort pipe request and return -116
</li><li>if wait succeeded, get transfer results via <a class="missing wiki">GetOverlappedResults?</a>() and return error or transfer length.
</li></ol><p>
So, if a transfer completes just after a timeout is detected in 2a, the entire transfer is lost.
</p>
<p>
There are currently a couple ways to avoid this:
1) Use the async transfer functions and usb_reap_async_nocancel()
2) Use the sync transfer functions from within their own thread and
always use INFINITE for the timeout.
</p>
<p>
<strong>Reported Error Codes</strong>
</p>
<p>
/* Connection timed out */
#define ETRANSFER_TIMEDOUT 116
</p>
<p>
Standard Error Codes from WDK crt errno.h and the explanation from MinGW are listed here. Take note that not all error codes below are used.
</p>
<pre class="wiki">
#define EPERM		1	/* Operation not permitted */ 
#define	ENOENT		2	/* No entry, ENOFILE, no such file or directory */
#define	ESRCH		3	/* No such process */
#define	EINTR		4	/* Interrupted function call */
#define	EIO		5	/* Input/output error */
#define	ENXIO		6	/* No such device or address */
#define	E2BIG		7	/* Arg list too long */
#define	ENOEXEC		8	/* Exec format error */
#define	EBADF		9	/* Bad file descriptor */
#define	ECHILD		10	/* No child processes */
#define	EAGAIN		11	/* Resource temporarily unavailable */
#define	ENOMEM		12	/* Not enough space */
#define	EACCES		13	/* Permission denied */
#define	EFAULT		14	/* Bad address */
#define	EBUSY		16	/* strerror reports "Resource device" */
#define	EEXIST		17	/* File exists */
#define	EXDEV		18	/* Improper link (cross-device link?) */
#define	ENODEV		19	/* No such device */
#define	ENOTDIR		20	/* Not a directory */
#define	EISDIR		21	/* Is a directory */
#define	EINVAL		22	/* Invalid argument */
#define	ENFILE		23	/* Too many open files in system */
#define	EMFILE		24	/* Too many open files */
#define	ENOTTY		25	/* Inappropriate I/O control operation */
#define	EFBIG		27	/* File too large */
#define	ENOSPC		28	/* No space left on device */
#define	ESPIPE		29	/* Invalid seek (seek on a pipe?) */
#define	EROFS		30	/* Read-only file system */
#define	EMLINK		31	/* Too many links */
#define	EPIPE		32	/* Broken pipe */
#define	EDOM		33	/* Domain error (math functions) */
#define	ERANGE		34	/* Result too large (possibly too small) */
#define	EDEADLK		36      /* Resource deadlock avoided */
#define	ENAMETOOLONG	38	/* Filename too long */
#define	ENOLCK		39	/* No locks available */
#define	ENOSYS		40	/* Function not implemented */
#define	ENOTEMPTY	41	/* Directory not empty */

</pre><h2 id="III.Functions">III. Functions</h2>
<p>
<strong>1. Core</strong>
</p>
<p>
These functions comprise the core of libusb. They are used by all applications that utilize libusb.
</p>
<hr />
<p>
usb_init()<br />
Name <br />
usb_init -- Initialize libusb<br />
Description<br />
void usb_init(void);<br />
</p>
<p>
Just like the name implies, usb_init sets up some internal structures. usb_init must be called before any other libusb functions.
</p>
<hr />
<p>
usb_find_busses()<br />
Name<br />
usb_find_busses -- Finds all USB busses on system<br />
Description<br />
int usb_find_busses(void);<br />
</p>
<p>
usb_find_busses will find all of the busses on the system. Returns the number of changes since previous call to this function (total of new busses and busses removed).
</p>
<hr />
<p>
usb_find_devices()<br />
Name<br />
usb_find_devices -- Find all devices on all USB devices<br />
Description<br />
int usb_find_devices(void);<br />
</p>
<p>
usb_find_devices() will find all of the devices on each bus. This should be called after usb_find_busses(). Returns the number of changes since the previous call to this function (total of new device and devices removed).
</p>
<hr />
<p>
usb_get_busses()<br />
Name<br />
usb_get_busses -- Return the list of USB busses found<br />
Description<br />
struct usb_bus *usb_get_busses(void);<br />
</p>
<p>
usb_get_busses() simply returns the value of the global variable usb_busses. This was implemented for those languages that support C calling convention and can use shared libraries, but don't support C global variables (like Delphi).
</p>
<hr />
<p>
usb_set_debug()<br />
Name<br />
usb_set_debug -- set debug message verbose level<br />
Description<br />
void usb_set_debug(int level);<br />
</p>
<p>
usb_set_debug() sets the debug message verbose level. You can set it to 4 to print the debug message which is quite verbose.
</p>
<blockquote>
<p>
0      LOG_OFF,
1        LOG_ERROR,
2        LOG_WARNING,
3        LOG_INFO,
4        LOG_DEBUG,
</p>
</blockquote>
<hr />
<p>
<strong>2. Device operations</strong>
</p>
<p>
This group of functions deal with the device. It allows you to open and close the device as well standard USB operations like setting the configuration, alternate settings, clearing halts and resetting the device. It also provides OS level operations such as claiming and releasing 
interfaces.
</p>
<hr />
<p>
usb_open()<br />
Name<br />
usb_open -- Opens a USB device<br />
Description<br />
usb_dev_handle *usb_open(struct *usb_device dev);<br />
</p>
<p>
usb_open() is to be used to open up a device for use. usb_open must be called before attempting to perform any operations to the device. Returns a handle used in future communication with the device.
</p>
<hr />
<p>
usb_close()<br />
Name<br />
usb_close -- Closes a USB device<br />
Description<br />
int usb_close(usb_dev_handle *dev);<br />
</p>
<p>
usb_close closes a device opened with usb_open. No further operations may be performed on the handle after usb_close is called. Returns 0 on success or &lt; 0 on error.
</p>
<hr />
<p>
usb_set_configuration()<br />
Name<br />
usb_set_configuration -- Sets the active configuration of a device<br />
Description<br />
int usb_set_configuration(usb_dev_handle *dev, int configuration);<br />
</p>
<p>
usb_set_configuration sets the active configuration of a device. The configuration parameter is the value as specified in the descriptor field bConfigurationValue. Returns 0 on success or &lt; 0 on error.
</p>
<blockquote>
<p>
<strong>Must be called</strong>!: usb_set_configuration must be called with a valid configuration (not 0) before you can claim the interface. This might not be necessary in the future. This behavior is different from Linux libusb-0.1.
</p>
</blockquote>
<hr />
<p>
usb_set_altinterface()<br />
Name<br />
usb_set_altinterface -- Sets the active alternate setting of the current interface<br />
Description<br />
int usb_set_altinterface(usb_dev_handle *dev, int alternate);<br />
</p>
<p>
usb_set_altinterface() sets the active alternate setting of the current interface. The alternate parameter is the value as specified in the descriptor field bAlternateSetting. Returns 0 on success or &lt; 0 on error.
</p>
<hr />
<p>
usb_resetep()<br />
Name<br />
usb_resetep -- Resets state for an endpoint<br />
Description<br />
int usb_resetep(usb_dev_handle *dev, unsigned int ep);<br />
</p>
<p>
usb_resetep resets all state (like toggles) for the specified endpoint. The ep parameter is the value specified in the descriptor field bEndpointAddress. Returns 0 on success or &lt; 0 on error.<br />
</p>
<blockquote>
<p>
<strong>Deprecated</strong>: usb_resetep is deprecated. You probably want to use usb_clear_halt.
</p>
</blockquote>
<hr />
<p>
usb_clear_halt()<br />
Name<br />
usb_clear_halt -- Clears any halt status on an endpoint<br />
Description<br />
int usb_clear_halt(usb_dev_handle *dev, unsigned int ep);<br />
</p>
<p>
usb_clear_halt() clears any halt status on the specified endpoint. The ep parameter is the value specified in the descriptor field bEndpointAddress. Returns 0 on success or &lt; 0 on error.
</p>
<hr />
<p>
usb_reset()<br />
Name<br />
usb_reset -- Resets a device<br />
Description<br />
int usb_reset(usb_dev_handle *dev);<br />
usb_reset() resets the specified device by sending a RESET down the port it is connected to. Returns 0 on success or &lt; 0 on error.<br />
</p>
<blockquote>
<p>
<strong>Causes re-enumeration</strong>: After calling usb_reset, the device will need to re-enumerate and thus requires you to find the new device and open a new handle. The handle used to call usb_reset() will no longer work.
</p>
</blockquote>
<hr />
<p>
usb_claim_interface()<br />
Name<br />
usb_claim_interface -- Claim an interface of a device<br />
Description<br />
int usb_claim_interface(usb_dev_handle *dev, int interface);<br />
</p>
<p>
usb_claim_interface() claims the interface with the Operating System. The interface parameter is the value as specified in the descriptor field bInterfaceNumber. Returns 0 on success or &lt; 0 on error.<br />
</p>
<blockquote>
<p>
<strong>Must be called</strong>!: usb_claim_interface must be called before you perform any operations related to this interface (like usb_set_altinterface, usb_bulk_write, etc).
</p>
</blockquote>
<p>
Return Codes for usb_claim_interface():<br />
code        description<br />
-EBUSY        Interface is not available to be claimed<br />
-ENOMEM        Insufficient memory<br />
</p>
<hr />
<p>
usb_release_interface()<br />
Name<br />
usb_release_interface -- Releases a previously claimed interface<br />
Description<br />
int usb_release_interface(usb_dev_handle *dev, int interface);<br />
</p>
<p>
usb_release_interface() releases an interface previously claimed with usb_claim_interface. The interface parameter is the value as specified in the descriptor field bInterfaceNumber. Returns 0 on success or &lt; 0 on error.<br />
</p>
<hr />
<h2 id="a3.ControlTransfers">3. Control Transfers</h2>
<p>
This group of functions allow applications to send messages to the default control pipe.
</p>
<hr />
<p>
usb_control_msg()<br />
Name<br />
usb_control_msg -- Send a control message to a device<br />
Description<br />
int usb_control_msg(usb_dev_handle *dev, int requesttype, int request, int value, int index, char *bytes, int size, int timeout);<br />
</p>
<p>
usb_control_msg() performs a control request to the default control pipe on a device. The parameters mirror the types of the same name in the USB specification. Returns number of bytes written/read or &lt; 0 on error.
</p>
<hr />
<p>
usb_get_string()<br />
Name<br />
usb_get_string -- Retrieves a string descriptor from a device<br />
Description<br />
int usb_get_string(usb_dev_handle *dev, int index, int langid, char *buf, size_t buflen);<br />
</p>
<p>
usb_get_string() retrieves the string descriptor specified by index and langid from a device. The string will be returned in Unicode as specified by the USB specification. Returns the number of bytes returned in buf or &lt; 0 on error.
</p>
<hr />
<p>
usb_get_string_simple()<br />
Name<br />
usb_get_string_simple -- Retrieves a string descriptor from a device using the first language<br />
Description<br />
int usb_get_string_simple(usb_dev_handle *dev, int index, char *buf, size_t buflen);<br />
</p>
<p>
usb_get_string_simple() is a wrapper around usb_get_string that retrieves the string description specified by index in the first language for the descriptor and converts it into C style ASCII. Returns number of bytes returned in buf or &lt; 0 on error.
</p>
<hr />
<p>
usb_get_descriptor()<br />
Name<br />
usb_get_descriptor -- Retrieves a descriptor from a device's default control pipe<br />
Description<br />
int usb_get_descriptor(usb_dev_handle *dev, unsigned char type, unsigned char index, void *buf, int size);<br />
</p>
<p>
usb_get_descriptor() retrieves a descriptor from the device identified by the type and index of the descriptor from the default control pipe. Returns number of bytes read for the descriptor or &lt; 0 on error.<br />
See usb_get_descriptor_by_endpoint() for a function that allows the control endpoint to be specified.<br />
</p>
<hr />
<p>
usb_get_descriptor_by_endpoint()<br />
Name<br />
usb_get_descriptor_by_endpoint -- Retrieves a descriptor from a device<br />
Description<br />
int usb_get_descriptor_by_endpoint(usb_dev_handle *dev, int ep, unsigned char type, unsigned char index, void *buf, int size);<br />
</p>
<p>
usb_get_descriptor_by_endpoint() retrieves a descriptor from the device identified by the type and index of the descriptor from the control pipe identified by ep. Returns number of bytes read for the descriptor or &lt; 0 on error.<br />
</p>
<hr />
<h2 id="a4.BulkTransfers">4. Bulk Transfers</h2>
<p>
This group of functions allow applications to send and receive data via bulk pipes.
</p>
<hr />
<p>
usb_bulk_write()<br />
Name<br />
usb_bulk_write -- Write data to a bulk endpoint<br />
Description<br />
int usb_bulk_write(usb_dev_handle *dev, int ep, char *bytes, int size, int timeout);<br />
</p>
<p>
usb_bulk_write() performs a bulk write request to the endpoint specified by ep. Returns number of bytes written on success or &lt; 0 on error.
</p>
<hr />
<p>
usb_bulk_read()<br />
Name<br />
usb_bulk_read -- Read data from a bulk endpoint<br />
Description<br />
int usb_bulk_read(usb_dev_handle *dev, int ep, char *bytes, int size, int timeout);<br />
</p>
<p>
usb_bulk_read() performs a bulk read request to the endpoint specified by ep. Returns number of bytes read on success or &lt; 0 on error.
</p>
<hr />
<h2 id="a5.InterruptTransfers">5. Interrupt Transfers</h2>
<p>
This group of functions allow applications to send and receive data via interrupt pipes.
</p>
<hr />
<p>
usb_interrupt_write()<br />
Name<br />
usb_interrupt_write -- Write data to an interrupt endpoint<br />
Description<br />
int usb_interrupt_write(usb_dev_handle *dev, int ep, char *bytes, int size, int timeout);<br />
</p>
<p>
usb_interrupt_write() performs an interrupt write request to the endpoint specified by ep. Returns number of bytes written on success or &lt; 0 on error.
</p>
<hr />
<p>
usb_interrupt_read()<br />
Name<br />
usb_interrupt_read -- Read data from a interrupt endpoint<br />
Description<br />
int usb_interrupt_read(usb_dev_handle *dev, int ep, char *bytes, int size, int timeout);<br />
</p>
<p>
usb_interrupt_read performs a interrupt read request to the endpoint specified by ep. Returns number of bytes read on success or &lt; 0 on error.
</p>
<hr />
<h2 id="a6.AsynchronousAPIandIsochronousTransfer">6. Asynchronous API and Isochronous Transfer</h2>
<p>
<strong>Windows Specific</strong>
</p>
<p>
libusb-win32 supports Isochronous Transfer through its Asynchronous API. The libusb-win32 Asynchronous API also supports the other transfer types like Control Transfer, Interrupt Transfer and Bulk Transfer.
</p>
<p>
int usb_isochronous_setup_async(usb_dev_handle *dev, void **context, unsigned char ep, int pktsize);<br />
</p>
<blockquote>
<p>
Allocates an asynchonous request for endpoint 'ep' and returns that request in 'context'.<br />
Returns 0 on success, &lt; 0 on failure.
</p>
</blockquote>
<p>
int usb_bulk_setup_async(usb_dev_handle *dev, void **context, unsigned char ep);<br />
</p>
<blockquote>
<p>
Allocates an asynchonous request for endpoint 'ep' and returns that request in 'context'.<br />
Returns 0 on success, &lt; 0 on failure.
</p>
</blockquote>
<p>
int usb_interrupt_setup_async(usb_dev_handle *dev, void **context, unsigned char ep);<br />
</p>
<blockquote>
<p>
Allocates an asynchonous request for endpoint 'ep' and returns that request in 'context'.<br />
Returns 0 on success, &lt; 0 on failure.
</p>
</blockquote>
<p>
int usb_submit_async(void *context, char *bytes, int size);<br />
</p>
<blockquote>
<p>
Submits a previously allocated request to the device. Data pointed to by 'bytes' of size 'size' will be written or read to or from the device depending on the endpoint's direction bit. <br />
Returns 0 on success, &lt; 0 on failure.
</p>
</blockquote>
<p>
int usb_reap_async(void *context, int timeout);<br />
</p>
<blockquote>
<p>
Waits for the request to finish. Returns the number of bytes written/read or &lt; 0 on failure.<br />
The request will be canceled if it doesn't complete within 'timeout' (in ms).
</p>
</blockquote>
<p>
int usb_reap_async_nocancel(void *context, int timeout);<br />
</p>
<blockquote>
<p>
Same as usb_reap_async() but doesn't cancel the request if it times out. Therefore you can try to reap it later. <br />
</p>
</blockquote>
<p>
int usb_cancel_async(void *context);<br />
   
</p>
<blockquote>
<p>
Cancels a request.
</p>
</blockquote>
<p>
int usb_free_async(void **context);<br />
</p>
<blockquote>
<p>
Frees a request.
</p>
</blockquote>
<p>
* Usage:
</p>
<pre class="wiki">
 char data[1024];
 void *request;
 int read;
 if(usb_bulk_setup_async(dev, &amp;request, 0x81) &lt; 0) {
   // error handling
 }
 if(usb_submit_async(request, data, sizeof(data)) &lt; 0) {
   // error handling
 }
 read =  usb_reap_async(request, 1000);
 if(read &gt;= 0)
 printf("read %d bytes\n", read);
 else
   // error handling
 usb_free_async(&amp;request);

</pre><h2 id="a7.NonPortable">7. Non Portable</h2>
<p>
These functions are non portable. They may expose some part of the USB API on one OS or perhaps more, but not all. They are all marked with the string _np at the end of the function name.
</p>
<p>
A C preprocessor macro will be defined if the function is implemented. The form is LIBUSB_HAS_ prepended to the function name, without the leading "usb_", in all caps. For example, if usb_get_driver_np is implemented, LIBUSB_HAS_GET_DRIVER_NP will be defined.
</p>
<p>
<strong>Linux Specific</strong>
</p>
<hr />
<p>
usb_get_driver_np()<br />
Name<br />
usb_get_driver_np -- Get driver name bound to interface<br />
Description<br />
int usb_get_driver_np(usb_dev_handle *dev, int interface, char *name, int namelen);<br />
</p>
<p>
This function will obtain the name of the driver bound to the interface specified by the parameter interface and place it into the buffer named name limited to namelen characters. Returns 0 on success or &lt; 0 on error. Implemented on Linux only.
</p>
<hr />
<p>
usb_detach_kernel_driver_np()<br />
Name<br />
usb_detach_kernel_driver_np -- Detach kernel driver from interface<br />
Description<br />
int usb_detach_kernel_driver_np(usb_dev_handle *dev, int interface);<br />
</p>
<p>
This function will detach a kernel driver from the interface specified by parameter interface. Applications using libusb can then try claiming the interface. Returns 0 on success or &lt; 0 on error. Implemented on Linux only.
</p>
<hr />
<p>
<strong>Windows Specific</strong>
</p>
<blockquote>
<p>
/* Windows specific functions */
</p>
</blockquote>
<p>
const struct usb_version *usb_get_version(void); <br />
</p>
<blockquote>
<p>
Return the library version.
</p>
</blockquote>
<p>
The following functions are related to driver installation (device driver mode of filter driver mode). Normally you should not use them. You can bundle the GUI Inf-Wizard with your application. Or you can choose to write your own driver installation applications. <a class="ext-link" href="http://libwdi.sf.net/"><span class="icon">libwdi</span></a> or <a class="ext-link" href="http://msdn.microsoft.com/en-us/library/ff544838%28v=VS.85%29.aspx"><span class="icon">WDK DIFx</span></a> can be used for that purpose. You can combine libwdi/DIFx with installers like <a class="ext-link" href="http://www.jrsoftware.org/isinfo.php"><span class="icon">Inno Setup</span></a> or <a class="ext-link" href="http://nsis.sourceforge.net/"><span class="icon">NSIS</span></a>.
</p>
<p>
#define LIBUSB_HAS_INSTALL_SERVICE_NP 1<br />
</p>
<blockquote>
<p>
int usb_install_service_np(void);<br />
void CALLBACK usb_install_service_np_rundll(HWND wnd, HINSTANCE instance, LPSTR cmd_line, int cmd_show);
</p>
</blockquote>
<p>
#define LIBUSB_HAS_UNINSTALL_SERVICE_NP 1<br />
</p>
<blockquote>
<p>
int usb_uninstall_service_np(void);<br />
void CALLBACK usb_uninstall_service_np_rundll(HWND wnd, HINSTANCE instance, LPSTR cmd_line, int cmd_show);
</p>
</blockquote>
<p>
#define LIBUSB_HAS_INSTALL_DRIVER_NP 1<br />
</p>
<blockquote>
<p>
int usb_install_driver_np(const char *inf_file);<br />
void CALLBACK usb_install_driver_np_rundll(HWND wnd, HINSTANCE instance, LPSTR cmd_line, int cmd_show);
</p>
</blockquote>
<p>
#define LIBUSB_HAS_TOUCH_INF_FILE_NP 1<br />
</p>
<blockquote>
<p>
int usb_touch_inf_file_np(const char *inf_file);<br />
void CALLBACK usb_touch_inf_file_np_rundll(HWND wnd, HINSTANCE instance, LPSTR cmd_line, int cmd_show);
</p>
</blockquote>
<p>
#define LIBUSB_HAS_INSTALL_NEEDS_RESTART_NP 1<br />
</p>
<blockquote>
<p>
int usb_install_needs_restart_np(void);
</p>
</blockquote>
<p>
More details to Be Added.
</p>
<h2 id="IV.Examples">IV. Examples</h2>
<p>
There are some non-intuitive parts of libusb v0.1 that aren't difficult, but are probably easier to understand with some examples.
</p>
<p>
<strong>Basic Examples</strong>
</p>
<p>
Before any communication can occur with a device, it needs to be found. This is accomplished by finding all of the busses and then finding all of the devices on all of the busses:
</p>
<pre class="wiki">    	struct usb_bus *busses;
    
    	usb_init();
    	usb_find_busses();
    	usb_find_devices();
    
    	busses = usb_get_busses();
</pre><p>
After this, the application should manually loop through all of the busess and all of the devices and matching the device by whatever criteria is needed:
</p>
<pre class="wiki">    	struct usb_bus *bus;
    	int c, i, a;
    
    	/* ... */
    
    	for (bus = busses; bus; bus = bus-&gt;next) {
    		struct usb_device *dev;
    
    		for (dev = bus-&gt;devices; dev; dev = dev-&gt;next) {
    			/* Check if this device is a printer */
    			if (dev-&gt;descriptor.bDeviceClass == 7) {
    				/* Open the device, claim the interface and do your processing */
    				...
    			}
    
    			/* Loop through all of the configurations */
    			for (c = 0; c &lt; dev-&gt;descriptor.bNumConfigurations; c++) {
    				/* Loop through all of the interfaces */
    				for (i = 0; i &lt; dev-&gt;config[c].bNumInterfaces; i++) {
    					/* Loop through all of the alternate settings */
    					for (a = 0; a &lt; dev-&gt;config[c].interface[i].num_altsetting; a++) {
    						/* Check if this interface is a printer */
    						if (dev-&gt;config[c].interface[i].altsetting[a].bInterfaceClass == 7) {
    						/* Open the device, set the alternate setting, claim the interface and do your processing */
    						   ...
    						}
    					}
    				}
    			}
    		}
    	}
</pre>
        
        
      </div>
    </div>
    <div id="altlinks">
      <h3>Download in other formats:</h3>
      <ul>
        <li class="last first">
          <a rel="nofollow" href="/apps/trac/libusb-win32/wiki/libusbwin32_documentation?format=txt">Plain Text</a>
        </li>
      </ul>
    </div>
    </div>
    <div id="footer" lang="en" xml:lang="en"><hr />
      <a id="tracpowered" href="http://trac.edgewall.org/"><img src="/apps/trac/libusb-win32/chrome/common/trac_logo_mini.png" height="30" width="107" alt="Trac Powered" /></a>
      <p class="left">
        Powered by <a href="/apps/trac/libusb-win32/about"><strong>Trac 0.11.2.1</strong></a><br />
        By <a href="http://www.edgewall.org/">Edgewall Software</a>.
      </p>
      <p class="right"></p>
    </div>
<!-- Footer -->
		</div>
        </div>
<!-- End Footer -->

    
<p class="copyright">&copy; 2013 SourceForge. All Rights Reserved.
SourceForge is a <a href="http://www.diceholdingsinc.com/phoenix.zhtml?c=211152&p=irol-landing">Dice Holdings, Inc.</a> company &nbsp;
<a href="http://slashdotmedia.com/terms-of-use">Terms of Use</a> -
<a href="http://slashdotmedia.com/privacy-statement/">Privacy Policy</a> -
<a href="http://slashdotmedia.com/opt-out-choices">Cookies/Opt Out</a>
</p>
    
    <script type="text/javascript">
	pageTracker._trackPageview();
    </script>
</body>
</html>
